Contents | Prev | Next | JDBCTM Guide: Getting Started

## 11 Clarifications

We have gotten several requests to clarify some aspects of the JDBC API. This chapter contains additional explanation of some features.

### 11.1 Connection.isClosed()

The `Connection.isClosed()` method is only guaranteed to return true after `Connection.closed()` has been called. `Connection.isClosed()` cannot be called, in general, to determine if a database connection is valid or invalid. A typical client can determine that a connection is invalid by catching the exception that is thrown when an operation is attempted.

### 11.2 Statement.setCursorName()

The `Statement.setCursorName()` method provides a way for an application to specify a cursor name for the cursor associated with the next result set produced by a statement. A result set's cursor name can be retrieved by calling `ResultSet.getCursorName().` If `Statement.setCursorName()` is called prior to creating a result set, then `ResultSet.getCursorName()` should always return the value specified in`Statement.setCursorName().`

We note that calling `Statement.setCursorName()` prior to creating a result set does not mean that the result set is updatable, in other words, positioned update or delete may not be allowed on a result set even if `Statement.setCursorName()` was called. By default , a result set is read-only.

The only use for a cursor name is to embed it in a SQL statement of the form

>     UPDATE ... WHERE CURRENT OF <cursor>

The cursor name provides a way to do a positioned update or delete. To enable positioned update and delete on a result set, a select query of the form

>     SELECT FOR UPDATE ... FROM ... WHERE ...

should be used to create the result set. If `Statement.setCursorName()` is not called to specify a cursor name, then the JDBC driver or underlying DBMS must generate a cursor name when a `SELECT FOR UPDATE` statement is executed, if positioned update/delete is supported. `ResultSet.getCursorName()`should return `null` if the result set is read-only and `Statement.setCursorName()` was not called to specify a cursor name.

### 11.3 Character conversion

JDBC driver implementations are expected to automatically convert the Java programming language unicode encoding of strings and characters to and from the character encoding of the database being accessed. The JDBC API does not define how to override the character encoding of a database. For example, the API does not define how to store unicode characters in an ASCII database.

### 11.4 Streams as input parameters

When an application passes a stream as an input value via a setXXX() or updateXXX() method, the application is responsible for maintaining the stream in a readable state until one of the following methods is called: PreparedStatement.execute(), executeQuery(), executeUpdate(), or executeBatch(), and ResultSet.insertRow() or updateRow(). A JDBC driver is not required to wait until one of these methods is called to read the stream value.

### 11.5 Result sets not created by a Statement

A `ResultSet` object that is created by a metadata operation is only required to be forward-only. Scrollability is not required for result sets produced by `DatabaseMetaData` operations.

Contents | Prev | Next

Copyright © 1996-1999 Sun Microsystems, Inc. All rights reserved.